!pr1
Volume Catalog for Corvus and Sider........Bob Sander-Cederlof

When I have a stack of floppies, I can quickly shuffle through them reading labels to find the two or three most likely to have the elusive file I want.  On a hard disk it is hard to read the labels....

The last time I had a Corvus sitting in this room, there was a program on the utility disk which would list the first file name from each volume.  If you were careful about making the first file name descriptive, it could act like a label.  Of course, nearly every floppy around here has a first file named HELLO.  Not too helpful.

Several years ago Bill Morgan wrote a program we published in AAL called the Catalog Arranger.  It allows you to re-arrange the filenames in any catalog to any order you wish, and to rename the files using any combination of upper/lower case, inverse, flashing, and control-characters.  I use Catalog Arranger to make a "title" file at the beginning of each hard disk volume.  (If you never heard of Catalog Arranger, you can type it in from AALs of October 1982 and January 1983.  It is also available on a Quarterly disk for only $15.)

Now that I don't have the Corvus, or its handy program for listing the names of the first file in each volume, I decided to write my own.  The program that follows prints out the volume number, two spaces, and then the name of the first file.  If the volume is empty, it prints "<<<EMPTY VOLUME>>>".  You can abort the listing by pressing RETURN or ESCAPE, or pause it by pressing any other key.

Lines 1090-1100 set the origin at $803 and cause the object program to be written on a BRUNnable file called CAT.  We write it at $803 rather than $800 so that Applesoft will work correctly after CAT is finished.  Applesoft gets upset if $800 has any non-zero value in it.

I used two monitor routines.  $FD8E prints a carriage return, and $FDED prints any character from the A-register.

I also used routines inside DOS.  $AFF7 reads the VTOC of the current volume, using the inverse volume number from the variable R.VOLUME.  If there is any error in trying to read the VTOC, DOS would normally go through its procedure of printing the message and returning to Applesoft.  We cannot allow that, so I install a temporary patch to make the error condition cause a return to my code with carry set.  If there is no error, carry will be clear.  The only likely error is that I am asking for the VTOC of a non-existing volume, which means I have already processed them all.  The patching, call, and de-patching take place in lines 1160-1220.  Line 1230 branches to my exit routine if there was an error reported.  

I also call on $B011 to read the first sector of the catalog.  If you call $B011 with carry clear it reads the first sector of the catalog; with carry set, it reads the next sector of the catalog.  The sector is read into a standard buffer at $B4BB-B5BA.   See "Beneath Apple DOS" for a complete description of the catalog sectors.

Lines 1270-1440 convert the volume number to decimal and print it out.  Lines 1450-1480 check for an empty directory.  If it is empty, lines 1740-1800 print the empty volume message.  Otherwise, lines 1490-1550 print the file name.  Right here my program could use some improvement.  It is possible for an empty volume to not look empty, because deleted files are not physically removed from the catalog.  The byte we check for an empty volume could have $FF in it, signifying a deleted file.  In this case my program should continue searching through the catalog for either the end or a non-deleted file.  I didn't think it was absolutely necessary, since I was using Catalog Arranger to remove all deleted files from the catalog and position the title line at the very top.

Line 1730 returns back to DOS by JMP $3D0.  This reminds me of glitch we all run into from time to time.  If you intend to BRUN a program from the command level of the assembler or of Applesoft, it needs to end with JMP $3D0.  Ending with an RTS will not do, because BRUN does not leave any return address on the stack.  On the other hand, if you intend to start the program by using a CALL or MGO or $...G command, it is all right to end with an RTS.  In fact, with a CALL from inside a running Applesoft program you MUST use an RTS.  Just something to watch out for.
